home *** CD-ROM | disk | FTP | other *** search
/ PD Collection CD 1 / PD Collection CD 1.iso / textual / agrep / Docs / agrep_txt next >
Text File  |  1994-08-24  |  13KB  |  283 lines
  1.  
  2.  
  3.  
  4.  AGREP(l)                                                           AGREP(l)
  5.                                 June 11, 1991
  6.  
  7.  
  8.  
  9.  NAME
  10.       agrep - search a file for a string or regular expression, with
  11.       approximate matching capabilities
  12.  
  13.  SYNOPSIS
  14.       agrep [ -#cdehilnpsvwxDIS ] pattern [ filename... ]
  15.  
  16.  DESCRIPTION
  17.       agrep searches the input filenames (standard input is the default) for
  18.       records containing strings which either exactly or approximately match
  19.       a pattern. A record is by default a line, but it can be defined
  20.       differently using the -d option (see below).  Normally, each record
  21.       found is copied to the standard output.  Approximate matching allows
  22.       finding records that contain the pattern with several errors including
  23.       substitutions, insertions, and deletions.  For example, Massechusets
  24.       matches Massachusetts with two errors (one substitution and one
  25.       insertion).  Running agrep -2 Massechusets foo outputs all lines in
  26.       foo containing any string with distance at most 2 from Massechusets.
  27.       agrep supports many kinds of queries including arbitrary wild cards,
  28.       sets of patterns, and in general, arbitrary regular expressions.  See
  29.       PATTERNS below.  It supports most of the options supported by the grep
  30.       family plus several more (but it is not 100% compatible with grep).
  31.       For more information on the algorithm used by agrep see Wu and Manber,
  32.       "Fast Text Searching With Errors," Technical report #91-11, Department
  33.       of Computer Science, University of Arizona, June 1991 (available by
  34.       anonymous ftp from cs.arizona.edu inside agrep/agrep.tar as agrep.ps).
  35.       As with the rest of the grep family, the characters `$', `^', `*',
  36.       `[', `^', `|', `(', `)', `!', `;', and `\' can cause unexpected
  37.       results when included in the pattern, as these characters are also
  38.       meaningful to the shell.  To avoid these problems, one should always
  39.       enclose the entire pattern argument in single quotes, i.e., 'pattern'.
  40.       Do not use double quotes (").  agrep works only on text (ascii) files.
  41.       If the file is binary, for example, then agrep will generate an error
  42.       message.  Only one error message will be generated even if the file
  43.       list contains many binary files. When agrep is applied to more than
  44.       one input file, the name of the file is displayed preceding each line
  45.       which matches the pattern.  The filename is not displayed when
  46.       processing a single file, so if you actually want the filename to
  47.       appear, use /dev/null as a second file in the list.
  48.  
  49.  OPTIONS
  50.       -#   # is a non-negative integer (at most 8) specifying the maximum
  51.            number of errors permitted in finding the approximate matches
  52.            (defaults to zero).  Generally, each insertion, deletion, or
  53.            substitution counts as one error.  It is possible to adjust the
  54.            relative cost of insertions, deletions and substitutions (see -I
  55.            -D and -S options).
  56.  
  57.       -c   Display only the count of matching lines.
  58.  
  59.       -d 'delim'
  60.  
  61.  
  62.  
  63.                                     - 1 -        Formatted:  August 24, 1994
  64.  
  65.  
  66.  AGREP(l)                                                           AGREP(l)
  67.                                 June 11, 1991
  68.  
  69.  
  70.  
  71.            Define delim to be the separator between two records.  The
  72.            default value is '$', namely a record is by default a line.
  73.            delim can be a string of size at most 8 (with possible use of ^
  74.            and $), but not a regular expression.  Text between two delim's
  75.            is considered as one record.  For example, -d '$$' defines
  76.            paragraphs as records and -d '^From ' defines mail messages as
  77.            records.  agrep matches each record separately.  This option does
  78.            not currently work with regular expressions.  delim cannot
  79.            currently contain special control characters.
  80.  
  81.       -e pattern
  82.            Same as a simple pattern argument, but useful when the pattern
  83.            begins with a `-'.
  84.  
  85.       -h   Do not display filenames.
  86.  
  87.       -i   Case-insensitive search - e.g., "A" and "a" are considered
  88.            equivalent.
  89.  
  90.       -l   List only the files that contain a match.
  91.  
  92.       -n   Each line that is printed is prefixed by its line number in the
  93.            file.
  94.  
  95.       -p   Find lines in the text that contain a supersequence of the
  96.            pattern.  For example,
  97.             agrep -p DCS foo will match "Department of Computer Science."
  98.            This option has the same function as -I0, which sets the cost of
  99.            insertion to zero.
  100.  
  101.       -s   Work silently, that is, display nothing except error messages.
  102.            This is useful for checking the error status.
  103.  
  104.       -v   Inverse mode - display only those lines that do not contain the
  105.            pattern.
  106.  
  107.       -w   Search for the pattern as a word - i.e., surrounded by non-
  108.            alphanumeric characters.  The non-alphanumeric must surround the
  109.            match;  they cannot be counted as errors.  For example, agrep -w
  110.            -1 car will match cars, but not characters.
  111.  
  112.       -x   The pattern must match the whole line.
  113.  
  114.       -Ik  Set the cost of an insertion to k (k is a non-negative integer).
  115.            This option does not currently work with regular expressions.
  116.  
  117.       -Dk  Set the cost of a deletion to k (k is a non-negative integer).
  118.            This option does not currently work with regular expressions.
  119.  
  120.       -Sk  Set the cost of a substitution to k (k is a non-negative
  121.            integer).  This option does not currently work with regular
  122.  
  123.  
  124.  
  125.                                     - 2 -        Formatted:  August 24, 1994
  126.  
  127.  
  128.  AGREP(l)                                                           AGREP(l)
  129.                                 June 11, 1991
  130.  
  131.  
  132.  
  133.            expressions.
  134.  
  135.  PATTERNS
  136.       agrep supports a large variety of patterns, including simple strings,
  137.       strings with classes of characters, sets of strings, wild cards, and
  138.       arbitrary regular expressions.
  139.  
  140.       Strings
  141.            any sequence of characters, including the special symbols `^' for
  142.            beginning of line and `$' for end of line.  The special
  143.            characters listed above ( `$', `^', `*', `[', `^', `|', `(', `)',
  144.            `!', and `\' ) should be preceded by `\' if they are to be
  145.            matched as regular characters.  For example, \^abc\\ corresponds
  146.            to the string ^abc\, whereas ^abc corresponds to the string abc
  147.            at the beginning of a line.
  148.  
  149.       Classes of characters
  150.            a list of characters inside [] (in order) corresponds to any
  151.            character from the list.  For example, [a-ho-z] is any character
  152.            between a and h or between o and z.  The symbol `^' inside []
  153.            complements the list.  For example, [^i-n] is the same as [a-ho-
  154.            z].  The symbol `.' stands for any symbol (don't care).  The
  155.            symbol `^' thus has two meanings, but this is consistent with
  156.            egrep.
  157.  
  158.       Boolean operations
  159.            agrep supports an `and' operation `;' and an `or' operation `,',
  160.            but not a combination of both.  For example, 'fast;network'
  161.            searches for all records containing both words.
  162.  
  163.       Wild cards
  164.            The symbol '#' is used to denote a wild card.  # matches zero or
  165.            any number of arbitrary characters.  For example, ex#e matches
  166.            example.  The symbol # is equivalent to .* in egrep.  In fact, .*
  167.            will work too, because it is a valid regular expression (see
  168.            below), but unless this is part of an actual regular expression,
  169.            # will work faster.
  170.  
  171.       Combination of exact and approximate matching
  172.            any pattern inside angle brackets <> must match the text exactly
  173.            even if the match is with errors.  For example, <mathemat>ics
  174.            matches mathematical with one error (replacing the last s with an
  175.            a), but mathe<matics> does not match mathematical no matter how
  176.            many errors we allow.
  177.  
  178.       Regular expressions
  179.            The syntax of regular expressions in agrep is in general the same
  180.            as that for egrep.  The union operation `|', Kleene closure `*',
  181.            and parentheses () are all supported.  Currently '+' is not
  182.            supported.  Regular expressions are currently limited to
  183.            approximately 30 characters (generally excluding meta
  184.  
  185.  
  186.  
  187.                                     - 3 -        Formatted:  August 24, 1994
  188.  
  189.  
  190.  AGREP(l)                                                           AGREP(l)
  191.                                 June 11, 1991
  192.  
  193.  
  194.  
  195.            characters).  Some options (-d, -w, -x, -D, -I, -S) do not
  196.            currently work with regular expressions.  The maximal number of
  197.            errors for regular expressions that use '*' or '|' is 4.
  198.  
  199.  EXAMPLES
  200.       agrep -2 -c ABCDEFG foo
  201.            gives the number of lines in file foo that contain ABCDEFG within
  202.            two errors.
  203.  
  204.       agrep -1 -D2 -S2 'ABCD#YZ' foo
  205.            outputs the lines containing ABCD followed, within arbitrary
  206.            distance, by YZ, with up to one additional insertion (-D2 and -S2
  207.            make deletions and substitutions too "expensive").
  208.  
  209.       agrep -5 -p abcdefghij /usr/dict/words
  210.            outputs the list of all words containing at least 5 of the first
  211.            10 letters of the alphabet in order.  (Try it:  any list starting
  212.            with academia and ending with sacrilegious must mean something!)
  213.  
  214.       agrep -1 'abc[0-9](de|fg)*[x-z]' foo
  215.            outputs the lines containing, within up to one error, the string
  216.            that starts with abc followed by one digit, followed by zero or
  217.            more repetitions of either de or fg, followed by either x, y, or
  218.            z.
  219.  
  220.       agrep -d '^From ' 'breakdown; (inter|arpa|bit)net' mbox
  221.            outputs all mail messages (the pattern '^From ' separates mail
  222.            messages in a mail file) that contain breakdown and one of either
  223.            internet, arpanet, or bitnet.
  224.  
  225.       agrep -d '$$' -1 '<word1> <word2>' foo
  226.            finds all paragraphs that contain word1 followed by word2 with
  227.            one error in place of the blank. In particular, if word1 is the
  228.            last word in a line and word2 is the first word in the next line,
  229.            then the space will be substituted by a newline symbol and it
  230.            will match.  Thus, this is a way to overcome separation by a
  231.            newline.  Note that -d '$$' (or another delim which spans more
  232.            than one line) is necessary, because otherwise agrep searches
  233.            only one line at a time.
  234.  
  235.       agrep '^agrep' <this manual>
  236.            outputs all the examples of the use of agrep in this man pages.
  237.  
  238.  SEE ALSO
  239.       ed(1), ex(1), grep(1V), sh(1), csh(1).
  240.  
  241.  BUGS
  242.       This is the first release of agrep.  Expect some bugs, especially for
  243.       more complicated patterns.  Any bug reports or comments will be
  244.       appreciated! Please mail them to sw@cs.arizona.edu or
  245.       udi@cs.arizona.edu There may be problems when control characters
  246.  
  247.  
  248.  
  249.                                     - 4 -        Formatted:  August 24, 1994
  250.  
  251.  
  252.  AGREP(l)                                                           AGREP(l)
  253.                                 June 11, 1991
  254.  
  255.  
  256.  
  257.       (e.g., <ctrl>A ) are used as part of a string or delimiter.  Regular
  258.       expressions do not support the '+' operator (match 1 or more instances
  259.       of the preceding token).  These can be searched for by using this
  260.       syntax in the pattern:
  261.  
  262.            'pattern(pattern)*'
  263.  
  264.       (search for strings containing one instance of the pattern, followed
  265.       by 0 or more instances of the pattern).  sometimes adds an empty line
  266.       to the output.  The following can cause an infinite loop: agrep
  267.       pattern * > output_file.  If the number of matches is high, they may
  268.       be deposited in output_file before it is completely read leading to
  269.       more matches of the pattern within output_file (the matches are
  270.       against the whole directory).  It's not clear whether this is a "bug"
  271.       (grep will do the same), but be warned.  patterns are currently
  272.       limited to approximately 30 characters.  Lines are limited to 1024
  273.       characters.  Records are limited to 8K, and may be truncated if they
  274.       are larger than that.
  275.  
  276.  DIAGNOSTICS
  277.       Exit status is 0 if any matches are found, 1 if none, 2 for syntax
  278.       errors or inaccessible files.
  279.  
  280.  
  281.  
  282.                                     - 5 -        Formatted:  August 24, 1994
  283.